This code is released as CodeWare, meaning that you are free to use it, in exchange for sending the author (See "Contacting the Author" below) a utility and/or piece of source code of similar value. You may distribute this code freely, as long as it is distributed as an entire package, without modifications!
If you use any of this code, please give Lane Roathe credit. Thanks!
If you make modifications you'd like to see in the distribution package, please feel free to send them to Lane w/a note. It just might happen.
Distribution
You should have recieved the following files in this distribution:
If you recieved an incomplete distribution, please contact the author. (See "Contacting the Author" below.) And, before writing, the source to the MacOS and DOS applications is not missing, it is not included because these sources rely on ouside libraries and are thus much more difficult to distribute. If you really have a need for the application sources, let me know. I do include the main source file for the DOS application to show how easy it is to modify the actual assembler to fit inside an application shell. (yes, those really are MacOS calls, and yes, they do work…)
Re–Distribution
Non–profit distribution is allowed/encouraged as long as it is distributed as an entire package, without modifications! For-profit distribution (which includes shareware collections sold in any manner other than at user’s groups) requires that you not only obey the collection requirements (see next paragraph) but you must also donate five (5) copies (at no cost) of the collecction to a high school of your choice, and send the author proof of same w/the authors complimentary copies.
If you want to include this software in some sort of software collection (i.e. CD, etc.) you are required to contact the author to insure you distribute the latest version(s), and that you send the author two (2) copies of the collection. (See "Contacting the Author" below.)
Neither Ideas From the Deep nor the program's author make any guarantees about the performance or reliability of this software. Any and all risk in it's use is your own, including loss of data or life.
Installation
For the compiler, copy the folder "DASM Plugins" to the “Plug Ins” folder in the Metrowerks folder.
To install the Application, just drag it to any folder you wish. You may also want to make an alias of the application and place it on your desktop. Then you can drag files to be assembled onto this alias.
Ideas From the Deep, Ltd. provides software design & engineering, web page services, artwork, and licensing of code modules. If you are looking for software or web page services, or are an independent contractor looking for a contact house, email us.
IFD Data Assembler: What it is
The IFD Data Assembler provides a means by which you can write "programs" that generate data. Our specific example of this is the IFD scripting language. Originally this was done on a PC and a true assembler was used there to write "code" in this language which assembled into p-code the engine interprets. Macintosh assemblers are unable to create plain data files (as best we could determine) so we were forced to create a suitable replacement. This is it.
What it isn’t
This is not an assembler in the traditional sense of the word. Assemblers have three basic forms of instructions: op-codes, pseudo-ops, and macros. The IFD Data assembler only has two: pseudo-ops and macros. In fact, of the many pseudo-ops available, only a few actually output data.
In other words, you won't be writing executable programs with this assembler! (Although if anyone is interested in adding this capability, we'll talk to you.)
A Brief Overview
The following reference is a brief attempt to document how the IFD Data Assembler works. The design goal for this project was to not only be able to assemble all of our current script code, but to be able to enhance it by allowing the inclusion of C header files. This allows us to create a single header file defining all of the relevant “equates” that can be used in both our script files, as well as our C code files. Obviously, this assembler does not handle all situations that might arise in a .h file, so you must restrict the contents of these files to #define and enum declarations of numeric expressions. (typedef’s will be skipped over.)
Please Note: This document assumes that the Pseudo-ops have not been renamed! OK, since we opened that can of worms, you might as well know that all pseudo-ops are defined in the STR# resource of the assembler plug-in file. If you do change any names, you must be sure to enter them in UPPERCASE!
In the IFD Data Assembler, all Pseudo-ops are case in-sensitive, while all symbols and macro declarations are case sensitive. (%%4—make this a preference?)
Each line in a Data Assembler file follows this format:
label pseudo-op operand ;comment
Spacing between each element can consist of any number of spaces or tabs, but all elements must be on the same line! A “line” consists of all characters between return characters. Unix files are processed by the IDE, and the assembler understands MS-DOS formatted files without modification. (A must for our development needs.)
Lines which are blank or begin with either a semi-colon or slash (i.e.., ; or //) are considered comments and are not processed. Comments on processed lines end processing for that line.
Example:
// Good comment
; good comment
/* bad comment, generates an error */
Labels are considered global, unless they begin with the local symbol character, which defaults to the period. Global symbols can be referenced anywhere during an assembly, including included files. Local symbols can only be referenced between the first global symbol above, and the first global symbol below, the occurrence of the local symbol. Global symbols can be declared only once in an assembly, while local labels may be declared as many times as desired, as long as each occurrence is outside the scope of all other occurrences.
Example:
Global 1
.local1
.local2
.local1 // ERROR! (already declared)
Global2
.local1
.local2
Global1 //ERROR! (previously declared)
Included in this distribution is a compressed example (TEST.SIT) which contains the test program used in writing this assembler. Please be sure to look these sources over, as they give you a good idea of how to use the assembler to it’s fullest.
Pseudo-op Reference
#include “filename”
This includes the designated file and assembles it before continuing to the next line. Used just as with the C statement, including use of ““ and <> search path definers. (Application does not use search paths!)
#define value
As with the C counterpart, but you can only define numeric expressions! (see below.)
typedef type def; [or] typedef struct { items; } def;
Typedefs are simply skipped over, and generate neither code nor labels, allowing use of C .h files.
label equ value [or] label = value
Equates a label to a value, which may be any valid expression.
{label} d?.? value{,value…}
Output data. DB & DC.B output bytes, DW & DC.W output words, DL, DD, & DC.L output longs, and DT & DC.S output text strings. These are the only pseudo-ops that actually output data! If the optional label is present, it is assigned to the value of the PC before any data is output. You may have any number of items on any given line separated by commas. Values are any legal expression.
{label} org value
Assigns the PC (Program Counter) to the expression ‘value’. If the optional label is present, it too is assigned this value. Please note that this effects only the PC, and not the position of output data, which always starts at offset zero, and works it’s way up, numerically.
{label} ds value
Similar to org, but adds “value” to the PC. Useful in creating assembly “structures”.
macro macroname
Defines a macro which can be used later by placing ‘macroname’ in the pseudo-op position and the macro’s parameters in the operand position. During assembly, the assembler takes each line between this macro start line and it’s matching end of macro line, replaces macro parameter uses with the appropriate replacement text, and compiles the line. Here is an example of a macro definition and usage:
End of macro marker. For every ‘macro’ statement, a matching ‘endm’ statement must follow.
outfile “filename”
Specifies the name of the file to which the data will be saved. The assembler defaults to outputting the file to the name of the source file with it’s extension replaced by the preferences extension text. Factory settings would create “text.bin” from “test.gor”. The legality of the filename specified by either method (extension replacement or outfile specification) is not checked by the assembler. Instead, if the filename is invalid the assembly will abort with a fatal error after completing. [%%4—find a way to pre-check to give “warning” message & save to some default filename?]
outtype data [or] rsrc [or] link
Define output type. data == data file, rsrc == resource file, link == linked resource (IDE only)
resinfo ‘type’, id#
Informs the compiler that you will be saving a resource. This pseudo-op overrides the preferences settings for output type, resource type, and resource id#. The type parameter is a four character sequence, just as you would use in a Macintosh C compiler, and the id# is any valid expression. Please remember that resource id#s are limited to shorts (16 bits) while all assembler values are longs (32 bits).
Expressions
Expressions are any legal numeric statement which includes constants (i.e., 123 or $FEED, or 0xDEAD), symbols (i.e., Global or .local), and operators (i.e., +, -, (, ), etc.…).
The order an expression is parsed is a bit odd. Consider:
100+50-25-75
The order of evalution is: 25-75, 50 - -50, 100 + 100. In other words, expressions are parsed right to left ( opposite standard parsing rules) but each individual case is left to right. So, the actual expression is:
100 + (50 - (25 - 75)) = 200
Because of the rather unusual parsing order, it is very advisable to group all operations within parenthasis to insure proper evaluation.
Other than that, the expression parser is pretty robust, and includes most operations you would expect to find in a C compiler. The following breakdown should cover everhting, but you may want to experiment, as the expression parser is the least scientifically tested portion of DASM. (Hey, I use it daily, but I’ve never written a good stress tester for the parser.)
Valid Constant identifiers are:
$ hexidecimal (base 16)
0x hexidecimal (base 16)
% binary (base 2)
‘xx’ long, composed of four (4) ASCII bytes (MacOS OSType & ResType) EX: ‘DLOG’ & ‘vers’
